Function Reference

_AD_Open

Opens a connection to Active Directory.

#Include <AD.au3>
_AD_Open([$sUserIdParam = "", $sPasswordParam = ""[, $sDNSDomainParam = "", $sHostServerParam = "", $sConfigurationParam = ""[, $iSecurity = 0]]])

Parameters

$sUserIdParam	Optional: UserId credential for authentication. This has to be a valid domain user
$sPasswordParam	Optional: Password for authentication
$sDNSDomainParam	Optional: Active Directory domain name if you want to connect to an alternate domain e.g. DC=microsoft,DC=com
$sHostServerParam	Optional: Name of Domain Controller if you want to connect to a different domain e.g. DC-Server1.microsoft.com If you want to connect to a Global Catalog append port 3268 e.g. DC-Server1.microsoft.com:3268 You can omit the servername e.g. only specify microsoft.com if you want to access the domain root
$sConfigurationParam	Optional: Configuration naming context if you want to connect to a different domain e.g. CN=Configuration,DC=microsoft,DC=com
$iSecurity	Optional: Specifies the security settings to be used. Can be a combination of the following: 0: No security settings are used (default) 1: Sets the connection property "Encrypt Password" to True to encrypt userid and password 2: The channel is encrypted using Secure Sockets Layer (SSL). AD requires that the Certificate Server be installed to support SSL

Return Value

Success: 1
Failure: 0, sets @error to:
    1 - (No longer used)
    2 - Creation of the COM object to the AD failed. @extended returns error code from ObjCreate
    3 - Open the connection to AD failed. @extended returns error code of the COM error handler.
    Generated if the User doesn't have query / modify access
    4 - Creation of the RootDSE object failed. @extended returns the error code received by the COM error handler.
    Generated when connection to the domain isn't successful. @extended returns -2147023541 (0x8007054B)
    5 - Creation of the DS object failed. @extended returns the error code received by the COM error handler
    6 - Parameter $sHostServerParam and $sConfigurationParam are required when $sDNSDomainParam is specified
    7 - Parameter $sPasswordParam is required when $sUserIdParam is specified
    8 - OpenDSObject method failed. @extended set to error code received from the OpenDSObject method.
    On Windows XP or lower this shows that $sUserIdParam and/or $sPasswordParam are invalid
    x - For Windows Vista and later: Win32 error code (decimal). To get detailed error information call function _AD_GetLastADSIError

Remarks

To close the connection to the Active Directory, use the _AD_Close function.

_AD_Open will use the alternative credentials $sUserIdParam and $sPasswordParam if passed as parameters.
$sUserIdParam has to be in one of the following forms (assume the samAccountName = DJ)
* Windows Login Name e.g. "DJ"
* NetBIOS Login Name e.g. "\DJ"
* User Principal Name e.g. "DJ@domain.com"
All other name formats have NOT been successfully tested (see section "Link").

Connection to an alternate domain (not the domain your computer is a member of) or if your computer is not a domain member
requires $sDNSDomainParam, $sHostServerParam and $sConfigurationParam as FQDN as well as $sUserIdParam and $sPasswordParam.
Example:
$sDNSDomainParam = "DC=subdomain,DC=example,DC=com"
$sHostServerParam = "servername.subdomain.example.com"
$sConfigurationParam = "CN=Configuration,DC=subdomain,DC=example,DC=com"

The COM error handler will be initialized only if there doesn't already exist another error handler.

If you specify $sUserIdParam as NetBIOS Login Name or User Principal Name and the OS is Windows Vista or later then _AD_Open will try to
verify the userid/password.
@error will be set to the Win32 error code (decimal). To get detailed error information please call _AD_GetlastADSIError.
For all other OS or if userid is specified as Windows Login Name @error=8.
This is OS dependant because Windows XP doesn't return useful error information.
For Windows Login Name all OS return success even when an error occures. This seems to be caused by secure authentification.

$iSecurity = 2 activates LDAP/SSL. LDAP/SSL uses port 636 by default.
Note that an SSL server certificate must be configured properly in order to use SSL.

If you want to connect to a specific DC in the current domain then just provide $sHostServerParam and let $sDNSDomainParam and $sConfigurationParam be blank.

Related

_AD_Close

See Also

http://msdn.microsoft.com/en-us/library/cc223499(PROT.10).aspx (Simple Authentication), http://msdn.microsoft.com/en-us/library/aa746471(VS.85).aspx (ADO)

Example

#AutoIt3Wrapper_AU3Check_Parameters= -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6
#AutoIt3Wrapper_AU3Check_Stop_OnWarning=Y
; *****************************************************************************
; Example 1
; Open a connection to the Active Directory; get the Fully Qualified Domain
; Name (FQDN) for the current user; close the connection.
; *****************************************************************************
#include <AD.au3>
#include <ButtonConstants.au3>
#include <GUIConstantsEx.au3>
#include <EditConstants.au3>
#include <WindowsConstants.au3>

Global $SUserID1, $SUserID2, $SUserId3, $SDNSDomain, $SHostServer, $SConfiguration, $SPassword, $SUserId, $aTEMP

; User is already a domain member
If @LogonDomain <> "" Then
; Open Connection to the Active Directory
_AD_Open()
If @error Then Exit MsgBox(16, "Active Directory Example Skript", "Function _AD_Open encountered a problem. @error = " & @error & ", @extended = " & @extended)
$SUserID1 = @UserName
$SUserID2 = @LogonDomain & "\" & @UserName
$SUserId3 = @UserName & "@" & @LogonDNSDomain
$SDNSDomain = $sAD_DNSDomain
$SHostServer = $sAD_HostServer
$SConfiguration = $sAD_Configuration
_AD_Close()
EndIf

#region ### START Koda GUI section ### Form=
Global $Form1_1 = GUICreate("Active Directory Functions - Example 1", 515, 290, 251, 112)
GUICtrlCreateLabel("UserId", 8, 12, 39, 21)
GUICtrlSetFont(-1, 8, 800, 0, "MS Sans Serif")
GUICtrlCreateLabel("Windows Login Name:", 96, 12, 131, 21)
Global $IRadio1 = GUICtrlCreateRadio("", 72, 8, 17, 21)
Global $IUserId1 = GUICtrlCreateInput($SUserID1, 241, 8, 259, 21)
GUICtrlCreateLabel("NetBIOS Login Name:", 96, 44, 131, 21)
Global $IRadio2 = GUICtrlCreateRadio("", 72, 40, 17, 21)
Global $IUserId2 = GUICtrlCreateInput($SUserID2, 241, 40, 259, 21)
GUICtrlCreateLabel("User Principal Name:", 96, 76, 131, 21)
Global $IRadio3 = GUICtrlCreateRadio("", 72, 72, 17, 21)
Global $IUserId3 = GUICtrlCreateInput($SUserId3, 241, 72, 259, 21)
GUICtrlCreateLabel("Password", 8, 108, 200, 21)
GUICtrlSetFont(-1, 8, 800, 0, "MS Sans Serif")
Global $IPassword = GUICtrlCreateInput("", 241, 104, 259, 21, $ES_PASSWORD)
GUICtrlCreateLabel("DNSDomain", 8, 140, 200, 21)
GUICtrlSetFont(-1, 8, 800, 0, "MS Sans Serif")
Global $IDNSDomain = GUICtrlCreateInput($SDNSDomain, 241, 140, 259, 21)
GUICtrlCreateLabel("HostServer", 8, 172, 200, 21)
GUICtrlSetFont(-1, 8, 800, 0, "MS Sans Serif")
Global $IHostServer = GUICtrlCreateInput($SHostServer, 241, 172, 259, 21)
GUICtrlCreateLabel("Configuration", 8, 204, 200, 21)
GUICtrlSetFont(-1, 8, 800, 0, "MS Sans Serif")
Global $IConfiguration = GUICtrlCreateInput($SConfiguration, 241, 204, 259, 21)
Global $BOK = GUICtrlCreateButton("Logon", 8, 246, 130, 33)
Global $BCancel = GUICtrlCreateButton("Cancel", 428, 246, 73, 33)

; User is already a domain member
If @LogonDomain <> "" Then
GUICtrlSetState($IRadio2, $GUI_CHECKED)
GUICtrlSetState($IPassword, $GUI_FOCUS)
EndIf

GUISetState(@SW_SHOW)
#endregion ### END Koda GUI section ###

While 1
Global $nMsg = GUIGetMsg()
Switch $nMsg
Case $GUI_EVENT_CLOSE, $BCancel
Exit
Case $BOK
$SPassword = GUICtrlRead($IPassword)
If $SPassword = "" Then
MsgBox(16, "Active Directory Functions", "Password is missing!")
GUICtrlSetState($IPassword, $GUI_FOCUS)
ContinueCase
EndIf
$SDNSDomain = GUICtrlRead($IDNSDomain)
$SHostServer = GUICtrlRead($IHostServer)
$SConfiguration = GUICtrlRead($IConfiguration)
If GUICtrlRead($IRadio1) = $GUI_CHECKED Then
$SUserId = GUICtrlRead($IUserId1)
EndIf
If GUICtrlRead($IRadio2) = $GUI_CHECKED Then
$SUserId = GUICtrlRead($IUserId2)
$aTEMP = StringSplit($SUserId, "\")
If $aTEMP[0] <> 2 Then
MsgBox(16, "Active Directory Functions", "Wrong format for NETBIOS name." & @CRLF & "Has to be 'Domain\Userid'.")
GUICtrlSetState($IUserId2, $GUI_FOCUS)
ContinueCase
EndIf
EndIf
If GUICtrlRead($IRadio3) = $GUI_CHECKED Then
$SUserId = GUICtrlRead($IUserId3)
If StringInStr($SUserId, "@") = 0 Then
MsgBox(16, "Active Directory Functions", "Wrong format for User Principal Name." & @CRLF & "Has to be e.g. 'Userid@domain.com'.")
GUICtrlSetState($IUserId3, $GUI_FOCUS)
ContinueCase
EndIf
EndIf
; Open Connection to the Active Directory
If _AD_Open($SUserId, $SPassword, $SDNSDomain, $SHostServer, $SConfiguration) Then
MsgBox(64, "Active Directory Functions", "Logon was succcessful!")
ElseIf @error <= 8 Then
MsgBox(16, "Active Directory Functions", "The logon was not succcessful!" & @CRLF & @CRLF & "@error: " & @error & ", @extended: " & @extended)
Else
MsgBox(16, "Active Directory Functions", "The logon was not succcessful!" & @CRLF & @CRLF & "@error: " & @error & ", @extended: " & @extended & _
@CRLF & @CRLF & "Extended error information will be displayed")
Global $aError = _AD_GetLastADSIError()
_ArrayDisplay($aError)
EndIf
; Close Connection to the Active Directory
_AD_Close()
EndSwitch
WEnd